home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1996 April / MacFormat CD Edition MF36 (April 1996).iso / Shareware City / Developers / Tools Plus - GUI⁄Event libs / Tools Plus 2.6.1a Evaluat'n Kit / Tools Plus 2.6.1a / User Manual / 14-System Polling (1 of 4) < prev    next >
INI File  |  1994-09-17  |  30KB  |  559 lines
  1. [Display using Monaco 9]
  2.  
  3.  
  4. 14  System Polling
  5. ``````````````````
  6.  
  7. This chapter deals entirely with system polling and events.  It details how Tools Plus reports events, and how your application should respond to them.  This chapter is laid out as follows:
  8.    • System polling is detailed
  9.    • Task switching is detailed
  10.    • The Macintosh’s event reporting and queuing mechanism is explained
  11.    • Automatic event filtering when a watch cursor is displayed is
  12.      explained
  13.    • Tools Plus’s event record and its fields are detailed
  14.    • Event modifier keys are explained (Caps Lock, Shift, Option,
  15.      Command and Control)
  16.    • The PollSystem function is detailed.  All possible event codes are
  17.      listed here.  PollSystem’s internal workings are also described.
  18.    • Each possible event is detailed, along with the correct response
  19.      that should be taken by your application
  20.    • A Field To Event Cross Reference table quickly identifies when each
  21.      field in the polling record is used
  22.    • The polling routine’s execution time is discussed for applications
  23.      in which speed is critical
  24.  
  25.  
  26.  
  27.  
  28.  
  29. What Is Polling?
  30. ````````````````
  31.   In the purest sense, polling is a periodic process in which your application asks what has happened?  This gives your application the ability to respond to its environment, as well as to its own internal mechanisms.  The Macintosh’s Toolbox Event Manager creates and manages those events, however, they are at a very low level and require a lot of work before your application can use them (they are simplified by Tools Plus).
  32.  
  33.   Your application must constantly poll the system and respond to the reported events, and it does so with Tools Plus’s polling routine, PollSystem.
  34.  
  35.   PollSystem is the heart-beat of Tools Plus.  It is called by your application to obtain events generated by the user, such as typing or clicking the mouse.  In fact, all events are obtained this way.  The big difference here is that PollSystem does everything it possibly can before handing an event back to your application.  Some events are processed internally and are never reported to your application, such as when the user types in an Editing Field (the field automatically processes the typing).  Other events are reported to your application, such as when the user clicks a button.  The events reported to your application are in a format that your application can readily use.
  36.  
  37.  
  38.  
  39.  
  40.  
  41. Task Switching
  42. ``````````````
  43.   With the introduction of System 5, MultiFinder made cooperative multi-tasking a reality on the Macintosh.  Cooperative, or “switched” multi-tasking as it is often called, lets several applications run simultaneously by cycling amongst all the tasks.  The term “cooperative” is used because each application must cooperate with all others by relinquishing control to give the others some processing time.
  44.  
  45.   Only one application can be active (the front most window) at a time under MultiFinder and System 7, even though, potentially, you may be able to see dozens of windows from multiple applications simultaneously.  Therefore, the active application is temporarily “suspended” when another application (or desk accessory) is activated.  Please note that suspended applications can also receive events and processing time.
  46.  
  47.   There are two kinds of “switches” that occur in cooperative multi-tasking: minor and major.  In a major switch, your application is either suspended when another application or desk accessory is activated, or resumed when your application is activated.  The doSuspend and doResume events report this occurrence to your application.  In a minor switch, your application is given some processing time, then it releases control to another application or desk accessory.
  48.  
  49.   PollSystem takes care of task switching.  When your application calls PollSystem, a major or minor switch always occurs.  You only need to concern yourself with minor switches by calling PollSystem as frequently as possible.  In other words, don’t let your application run for ten seconds before calling PollSystem, or other applications will work jerkily, or worse yet, appear to mysteriously “hang” when in actuality they just aren’t getting enough cooperation from your application.  The doSuspend and doResume events detail how your application should respond to a major switch.
  50.  
  51.   See the SIZE resource to specify how your application will behave while suspended, and during the transition from being active to inactive or vice versa.
  52.  
  53.  
  54.  
  55.  
  56.  
  57. Background Processing
  58. `````````````````````
  59.   Applications written with Tools Plus can easily be made to do “background processing,” that is, performing an on-going process while waiting for events.  An example of this is repaginating a word-processing document, or searching a large file for specific records.
  60.  
  61.   When PollSystem returns with a value of false, it indicates that no event has occurred.  This is commonly called a “null event.”  Usually, your application won’t do anything other than idle in the main event loop.  If your application does background processing, it should do its work only when it receives a doNothing event.  A single cycle of your application’s background process should take no longer than 1/60 of a second.  Otherwise, other applications may run sluggishly or in spurts and jumps.
  62.  
  63.   You can set the rate at which your application receives doNothing events by using the SetNullTime routine.  The WaitAvail routine can be used to determine if the Macintosh your application is running on supports scheduled doNothing events.
  64.  
  65.  
  66.  
  67.  
  68.  
  69. Macintosh Events
  70. ````````````````
  71.   The Toolbox Event Manager, as described in chapter 8 of Inside Macintosh Volume I, is the link between your application and its user, and its machine environment.  Whenever the user types a key on the keyboard or numeric keypad, presses the mouse button, or inserts a disk in the disk drive, the Macintosh makes your application aware of this by means of an event.
  72.  
  73.   In addition to monitoring the user’s actions, the Macintosh’s Toolbox Event Manager also detects other types of events that serve to inform your application as to “what is happening.”  Such an event is reported when a partially obscured window is uncovered and its contents need to be redrawn (update event).
  74.  
  75.   The Toolbox Event Manager’s events contain an event code that identifies the type of event.  Event codes are available as constants.  Later, you will learn how the Macintosh’s Toolbox Event Manager’s events are automatically translated into Tools Plus events.  The list below is for reference purposes only, since your application will likely never make use of the Toolbox Event Manager’s events directly.
  76.  
  77.   CONST   
  78.     nullEvent      =0;    {no event detected                      }
  79.     mouseDown      =1;    {mouse button was pressed down          }
  80.     mouseUp        =2;    {mouse button was released              }
  81.     keyDown        =3;    {a key was pressed                      }
  82.     keyUp          =4;    {a key was released                     }
  83.     autoKey        =5;    {a key was held down and is repeating   }
  84.     updateEvt      =6;    {a window must be updated (refreshed)   }
  85.     diskEvt        =7;    {a disk was inserted                    }
  86.     activateEvt    =8;    {a window was activated or deactivated  }
  87.     networkEvt     =10;   {network                                }
  88.     driverEvt      =11;   {device driver                          }
  89.     app1Evt        =12;   {application-defined event number 1     }
  90.     app2Evt        =13;   {application-defined event number 2     }
  91.     app3Evt        =14;   {application-defined event number 3     }
  92.     app4Evt        =15;   {appl-defined event 4 / MultiFinder’s   }
  93.                           {  and Switcher’s Suspend/Resume event  }
  94.     osEvt          =15;   {Operating-system event (System 7)      }
  95.     kHighLevelEvent=23;   {High-level event (System 7)            }
  96.  
  97.  
  98.  
  99.  
  100.  
  101. Watch Cursor -- a busy system
  102. `````````````````````````````
  103.   The watch cursor is used to indicate a long wait, such as when a lengthy process is being conducted or when printing is being done.  Your application can display the watch cursor by calling CursorShape(watchCursor).
  104.  
  105.   While the watch cursor is displayed, your application may choose not to call PollSystem, since it doesn’t care what the user is doing and will want to ignore mouse clicks and typing anyway.  Unfortunately, this does not give the user the opportunity to halt a lengthy process, nor does it give other applications running under MultiFinder or System 7 any processing time.  Tools Plus solves this dilemma by shifting into a busy mode when the watch cursor is displayed.
  106.  
  107.   When your application displays the watch cursor, subsequent calls to PollSystem will filter out (discard) the effects of, and the events that may be generated by the user clicking the mouse or typing.  The exception to this, of course, is when the user types Command-. which tells your application to halt the process.  This lets your application call PollSystem regularly while it is busy conducting a lengthy task, knowing that any key or mouse event is meaningful (it indicates that the user wants to halt the process).  Your application may choose not to call PollSystem or to ignore the Command-. key if it’s busy only for a very short time.
  108.  
  109.   When your application is finished its lengthy process, it can either change the cursor itself or call ResetCursor to change the cursor to its appropriate shape according to its position on the screen.
  110.  
  111. Note: When the watch cursor is displayed, your application may receive
  112.       Tools Plus events that are unrelated to mouse clicks or typing,
  113.       such as redrawing a window (doRefresh) or a disk insert event.
  114.  
  115. Warning: If your application is running under MultiFinder or System 7,
  116.          it is possible to switch to another application while a watch
  117.          cursor is displayed unless your active window is of type
  118.          dBoxProc.
  119.  
  120.  
  121.  
  122.  
  123.  
  124. The Event Queue
  125. ```````````````
  126.   When events are generated, they are stored in an event queue.  When your application is ready to process them, the oldest event is removed from the queue and processed first.  This journaling mechanism lets the Macintosh remember a series of rapidly occurring events and store them until your application is ready to process them.
  127.  
  128.   Events have a certain priority, meaning that some events will be processed before others, regardless of when they were actually generated.  Their priority is as such:
  129.  
  130.   1. activate/deactivate a window
  131.  
  132.   2. mouse-down/up, key down/up, disk insert, network driver,
  133.      application-defined events (first in first out)
  134.  
  135.   3. auto-key (key pressed and held, causing it to repeat)
  136.  
  137.   4. update a window (refresh a window in front-to-back order)
  138.  
  139.   The priority of events insures that illogical events are not reported.  For instance, the user may click twice in a window’s close box before an application gets around to processing the event.  The first click will signal your application to close the window.  The second click will not be reported as a click in a non-existent (closed) window.  The second click’s location will be analyzed after the window is closed, and reported accordingly.
  140.  
  141.   Tools Plus works in an identical manner when interacting with the event queue.  In fact, Tools Plus obtains events from the Macintosh’s Toolbox Event Manager and translates them into something useful before reporting them to your application.
  142.  
  143. Note: The event queue can store a maximum of 20 events.  If your
  144.       application is so busy that it lets more than 20 events accumulate
  145.       in the queue, the oldest events is discarded to make room for
  146.       the new ones.
  147.  
  148.  
  149.  
  150.  
  151.  
  152. Tools Plus Event Record
  153. ```````````````````````
  154.   Whenever Tools Plus detects an event that cannot be processed automatically, it provides your application with the event’s information in the form of an event record.  Although the event record looks cumbersome, it is logically organized and is very easy to use.
  155.  
  156.   The entire record accounts for every type of event that can possibly occur.  During any one specific event, your application will only need to access one or two of these fields.  Later in this chapter when you are told how to respond to the various Tools Plus events, you will also be told which fields in the event record hold pertinent information.
  157.  
  158.   The event record is defined as follows (C first, then Pascal):
  159.  
  160.  
  161. /*= Polling record's "event modifiers" info*/
  162.   union TPModifiersRec {             /*This variable record contains  */
  163.                                      /*  an event's "modifiers" in 2  */
  164.                                      /*  formats…                     */
  165.                                      /*  • Macintosh Event:           */
  166.     short Num;                       /*      integer (bit operations  */
  167.                                      /*      required)                */
  168.                                      /*  • Modifier integer parsed    */
  169.     struct {                         /*    into components:           */
  170.       unsigned short bit15 :1;       /* (reserved bit)                */
  171.       unsigned short bit14 :1;       /* (reserved bit)                */
  172.       unsigned short bit13 :1;       /* (reserved bit)                */
  173.       unsigned short ControlKey :1;  /* Control key was down at event */
  174.       unsigned short OptionKey :1;   /* Option key was down at event  */
  175.       unsigned short CapsLock :1;    /* Caps Lock was down at event   */
  176.       unsigned short ShiftKey :1;    /* Shift key was down at event   */
  177.       unsigned short CmdKey :1;      /* Command key was down at event */
  178.       unsigned short MouseUp :1;     /* Mouse button was UP at event  */
  179.       unsigned short bit6 :1;        /* (reserved bit)                */
  180.       unsigned short bit5 :1;        /* (reserved bit)                */
  181.       unsigned short bit4 :1;        /* (reserved bit)                */
  182.       unsigned short bit3 :1;        /* (reserved bit)                */
  183.       unsigned short bit2 :1;        /* (reserved bit)                */
  184.       unsigned short bit1 :1;        /* (reserved bit)                */
  185.       unsigned short bit0 :1;        /* (reserved bit)                */
  186.     } Bits;                          /*                               */
  187.   };
  188.   typedef union TPModifiersRec TPModifiersRec;
  189. /*= Polling record's "button" info*/
  190.   struct TPPollButtonRec {
  191.     short Num;                       /*Button number                  */
  192.     Boolean DoubleClick;             /*Did a double-click occur in the*/
  193.   };                                 /*  button?                      */
  194.   typedef struct TPPollButtonRec TPPollButtonRec;
  195. /*= Polling record's "scroll bar" info*/
  196.   struct TPPollScrollBarRec {
  197.     short Num;                       /*Scroll bar number              */
  198.     short Part;                      /*Scroll bar's part              */
  199.   };
  200.   typedef struct TPPollScrollBarRec TPPollScrollBarRec;
  201. /*= Polling record's "list box" info*/
  202.   struct TPPollListBoxRec {
  203.     short Num;                       /*List box number                */
  204.     Boolean DoubleClick;             /*Did a double-click occur in a  */
  205.   };                                 /*  line?                        */
  206.   typedef struct TPPollListBoxRec TPPollListBoxRec;
  207. /*= Polling record's "menu" info*/
  208.   struct TPPollMenuRec {
  209.     short Num;                       /*Menu number                    */
  210.     short Item;                      /*Menu item number               */
  211.   };
  212.   typedef struct TPPollMenuRec TPPollMenuRec;
  213. /*= Polling record's "key-stroke" info*/
  214.   struct TPPollKeyRec {
  215.     short Code;                      /*Key number of key-stroke       */
  216.     char Chr;                        /*Character generated by key     */
  217.     Byte Unused;                     /* (reserved byte)               */
  218.   };
  219.   typedef struct TPPollKeyRec TPPollKeyRec;
  220. /*= Polling record's “mouse location and time” info for mouse-down and*/
  221. /*  mouse-up events                                                   */
  222.   struct TPPollMousePointRec {
  223.     Point Where;                     /*Event location in local co-    */
  224.                                      /*  ordinates                    */
  225.     long When;                       /*Event time in ticks from boot  */
  226.                                      /*  (1/60 sec)                   */
  227.     TPModifiersRec Modifiers;        /*Event modifiers                */
  228.   };
  229.   typedef struct TPPollMousePointRec TPPollMousePointRec;
  230. /*= Polling record's "mouse click/drag" info*/
  231.   struct TPPollMouseRec {
  232.     short What;                      /*What type of mouse event (click*/
  233.                                      /*  or drag?)                    */
  234.     TPPollMousePointRec Down[3];     /*Where & when did the mouse-down*/
  235.                                      /*  occur                        */
  236.     TPPollMousePointRec Up[3];       /*Where & when did the mouse-up  */
  237.                                      /*  occur                        */
  238.     Point Where;                     /*Current mouse location in local*/
  239.   };                                 /*  co-ordinates                 */
  240.   typedef struct TPPollMouseRec TPPollMouseRec;
  241. /*= POLLING record for Tools Plus*/
  242.   struct TPPollRecord {              /*Tools Plus Polling record…     */
  243.     short What;                      /*What type of event?            */
  244.     short Window;                    /*Window number of the event     */
  245.     TPPollButtonRec Button;          /*Button number & double-click   */
  246.                                      /*  status                       */
  247.     TPPollScrollBarRec ScrollBar;    /*Scroll bar number & scroll bar */
  248.                                      /*  part                         */
  249.     short Field;                     /*Field number of event          */
  250.     TPPollListBoxRec ListBox;        /*List box number & double-click */
  251.                                      /*  status                       */
  252.     TPPollMenuRec Menu;              /*Menu number/menu item of an    */
  253.                                      /*  event                        */
  254.     TPPollKeyRec Key;                /*Character generated by key     */
  255.                                      /*  stroke                       */
  256.     TPPollMouseRec Mouse;            /*Click/drag info: [1..3] where &*/
  257.                                      /*  when                         */
  258.     TPModifiersRec Modifiers;        /*Modifier flags                 */
  259.     EventRecord Event;               /*Macintosh Toolbox Event (raw)  */
  260.   };
  261.   typedef struct TPPollRecord TPPollRecord;
  262.   typedef TPPollRecord *TPPollPointer;/*Pointer to a Polling record   */
  263.  
  264.  
  265.  
  266. type
  267. {= Polling record's "event modifiers" info}
  268.   TPModifiersRec = packed record       {This variable record contains  }
  269.                                        {  an event's "modifiers" in 2  }
  270.     case integer of                    {  formats…                     }
  271.       0: (                             {  • Macintosh Event:           }
  272.         Num: integer                   {      integer (bit operations  }
  273.       );                               {      required)                }
  274.       1: (                             {  • Modifier integer parsed    }
  275.                                        {    into components:           }
  276.         bit15, bit14, bit13: boolean;  { (reserved bits)               }
  277.         ControlKey: boolean;           { Control key was down at event }
  278.         OptionKey: boolean;            { Option key was down at event  }
  279.         CapsLock: boolean;             { Caps Lock was down at event   }
  280.         ShiftKey: boolean;             { Shift key was down at event   }
  281.         CmdKey: boolean;               { Command key was down at event }
  282.         MouseUp: boolean;              { Mouse button was UP at event  }
  283.         bit6, bit5, bit4, bit3, bit2,  { (reserved bits)               }
  284.         bit1,bit0: boolean;            {                               }
  285.       );                               {                               }
  286.     end;
  287. {= Polling record's “button” info}
  288.   TPPollButtonRec = record
  289.     Num: integer;                      {Button number                  }
  290.     DoubleClick: boolean               {Did a double-click occur in the}
  291.    end;                                {  button?                      }
  292. {= Polling record’s “scroll bar” info}
  293.   TPPollScrollBarRec = record
  294.     Num: integer;                      {Scroll bar number              }
  295.     Part: integer                      {Scroll bar’s part              }
  296.   end;
  297. {= Polling record’s “list box” info}
  298.   TPPollListBoxRec = record
  299.     Num: integer;                      {List box number                }
  300.     DoubleClick: boolean               {Did a double-click occur in a  }
  301.   end;                                 {  line?                        }
  302. {= Polling record’s “menu” info}
  303.   TPPollMenuRec = record
  304.     Num: integer;                      {Menu number                    }
  305.     Item: integer                      {Menu item number               }
  306.   end;
  307. {= Polling record’s “key-stroke” info}
  308.   TPPollKeyRec = packed record
  309.     Code: integer;                     {Key number of key-stroke       }
  310.     Chr: char;                         {Character generated by key     }
  311.     Unused: byte;                      { (reserved byte)               }
  312.   end;
  313. {= Polling record’s “mouse location and time” info for mouse-down and  }
  314. {  mouse-up events.                                                    }
  315.   TPPollMousePointRec = record
  316.     Where: point;                      {Event location in local co-    }
  317.                                        {  ordinates.                   }
  318.     When: longint;                     {Event time in ticks from boot  }
  319.                                        {  (1/60 sec)                   }
  320.     Modifiers: TPModifiersRec;         {Event modifiers                }
  321.   end;
  322. {= Polling record’s “mouse click/drag” info}
  323.   TPPollMouseRec = record
  324.     What: integer;                     {What type of mouse event (down }
  325.                                        {  or up)?                      }
  326.     Down: array[1..3] of TPPollMousePointRec; {Where & when did the    }
  327.                                               {  mouse-down occur?     }
  328.     Up: array[1..3] of TPPollMousePointRec;   {Where & when did the    }
  329.                                               {  mouse-up occur?       }
  330.     Where: point;                      {Current mouse location in local}
  331.   end;                                 {  co-ordinates.                }
  332.  
  333. {= POLLING record for “Tools Plus” }
  334.   TPPollRecord = record
  335.     What: integer;                     {What type of event?            }
  336.     Window: integer;                   {Event’s window number          }
  337.     Button: TPPollButtonRec;           {Button number & double-click   }
  338.                                        {  status.                      }
  339.     ScrollBar: TPPollScrollBarRec;     {Scroll bar number & scroll bar }
  340.                                        {  part.                        }
  341.     Field: integer;                    {Field number of event          }
  342.     ListBox: TPPollListBoxRec;         {List box number/double-click   }
  343.                                        {  status.                      }
  344.     Menu: TPPollMenuRec;               {Menu number/menu item of an    }
  345.                                        {  event.                       }
  346.     Key: TPPollKeyRec;                 {Key number & character of key- }
  347.                                        {  stroke.                      }
  348.     Mouse: TPPollMouseRec;             {Click/drag info: [1..3] where &}
  349.                                        {  when.                        }
  350.     Modifiers: TPModifiersRec;         {Modifier flags                 }
  351.     Event: EventRecord                 {Pascal event record            }
  352.   end;
  353.   TPPollPointer = ^TPPollRecord;       {Pointer to a Polling record, in}
  354.                                        {  case you want to reduce      }
  355.                                        {  global variable memory.      }
  356.  
  357.  
  358.  
  359.  
  360.  
  361. Event Record Fields
  362. ```````````````````
  363.   The event record’s structure is best explained by detailing each subrecord and field with a programmer’s approach.  This explanation looks at the event record in detail, starting from the record level and ending with fields.
  364.  
  365.   Your application should define a variable or pointer than lets it use the polling record.  In the following text, the assumption has been made that the variable is called Poll.  If your application uses a pointer, replace Poll with Poll^ in the text.
  366.  
  367.   Note that all fields are not valid at the same time.  For example, the window field would not contain a valid number when a menu event was reported, because menus work independently of windows.  A “Field to Event Cross Reference” is included later in this section, and it lists each field and the events that make use of it.
  368.  
  369.  
  370. Poll
  371. ````
  372.   This variable is the entire polling record, and is of TPPollRecord type (it is a TPPollPointer type if your application is using a pointer to the record)
  373.  
  374.  
  375. Poll.What
  376. `````````
  377.   Event Code: Explains what type of event has occurred.  This field is used by your application to decide what action should be taken, and what other fields contain pertinent event information.
  378.  
  379.  
  380. Poll.Window
  381. ```````````
  382.   Window Number: Window number on which the event occurred.
  383.  
  384.  
  385. Poll.Button
  386. ```````````
  387.   Button Record
  388.  
  389.  
  390. Poll.Button.Num
  391. ```````````````
  392.   Button Number: Button number that was clicked by the user.
  393.  
  394.  
  395. Poll.Button.DoubleClick
  396. ```````````````````````
  397.   Button’s Double-Click Status: Was the button double-clicked?
  398.  
  399.  
  400. Poll.ScrollBar
  401. ``````````````
  402.   Scroll Bar Record
  403.  
  404.  
  405. Poll.ScrollBar.Num
  406. ``````````````````
  407.   Scroll Bar Number: Scroll bar number that was clicked by the user.  This does not include a scroll bar that is part of a list box.
  408.  
  409.  
  410. Poll.ScrollBar.Part
  411. ```````````````````
  412.   Scroll Bar Part: Part of scroll bar that was clicked by user (up arrow, down arrow, “page up” region, “page down” region, thumb)
  413.  
  414.  
  415. Poll.Field
  416. ``````````
  417.   Editing Field Number: Editing field that was clicked by the user.
  418.  
  419.  
  420. Poll.ListBox
  421. ````````````
  422.   List Box Record
  423.  
  424.  
  425. Poll.ListBox.Num
  426. ````````````````
  427.   List Box Number: List box number that was clicked by the user.
  428.  
  429.  
  430. Poll.ListBox.DoubleClick
  431. ````````````````````````
  432.   List Box’s Double-Click Status: Was a line in the list box double-clicked?
  433.  
  434.  
  435. Poll.Menu
  436. `````````
  437.   Menu Record
  438.  
  439.  
  440. Poll.Menu.Num
  441. `````````````
  442.   Menu Number: Menu number that was selected by the user.  This could be a pull-down menu, a hierarchical menu, or a pop-up menu.
  443.  
  444.  
  445. Poll.Menu.Item
  446. ``````````````
  447.   Menu Item: Item number that was selected by the user.
  448.  
  449.  
  450. Poll.Key
  451. ````````
  452.   Key Record
  453.  
  454.  
  455. Poll.Key.Code
  456. `````````````
  457.   Key Number: Number of the key that was pressed, released, or is auto-repeating.  This key code is a key number that is not affected by the Caps Lock, Shift, Option, Command and Control modifiers.
  458.  
  459.  
  460. Poll.Key.Chr
  461. ````````````
  462.   Key Character: Character resulting from a key that was pressed, released, or is auto-repeating.  This character is altered by the Caps Lock, Shift, Option, Command and Control modifiers.
  463.  
  464.  
  465. Poll.Mouse
  466. ``````````
  467.   Mouse Activity Record
  468.  
  469.  
  470. Poll.Mouse.What
  471. ```````````````
  472.   Mouse Event Code: Type of mouse event has occurred (i.e. single, double, triple-click, dragging, etc.).  This field is used by your application to decide what action should be taken, and which other fields in the mouse record contain pertinent information.
  473.  
  474.  
  475. Poll.Mouse.Down
  476. ```````````````
  477.   Mouse-Down Array Record: The elements of the array contain the first, second and third mouse-down events of a single, double, or triple-click, or drag.
  478.  
  479.  
  480. Poll.Mouse.Down[1].Where
  481. ````````````````````````
  482.   Mouse Down Location: Location of 1st mouse-down in a single, double, or triple-click, or drag.  Window’s local co-ordinates are used.
  483.  
  484.  
  485. Poll.Mouse.Down[1].When
  486. ```````````````````````
  487.   Mouse Down Time: Time of 1st mouse-down.  Number of “ticks” since startup.
  488.  
  489.  
  490. Poll.Mouse.Down[1].Modifiers
  491. ````````````````````````````
  492.   Mouse Down Modifier Record: Event modifiers at the time of the 1st mouse-down event.  See the note on modifiers below.
  493.  
  494.  
  495. Poll.Mouse.Down[2]…
  496. ```````````````````
  497.   Mouse-Down Array Record: Same fields, but for 2nd mouse-down in a double, or triple-click, or drag.
  498.  
  499.  
  500. Poll.Mouse.Down[3]…
  501. ```````````````````
  502.   Mouse-Down Array Record: Same fields, but for 3rd mouse-down in a triple-click, or drag.
  503.  
  504.  
  505. Poll.Mouse.Up
  506. `````````````
  507.   Mouse-Up Array Record: The elements of the array contain the first, second and third mouse-up events of a single, double, or triple-click, or drag.
  508.  
  509.  
  510. Poll.Mouse.Up[1].Where
  511. ``````````````````````
  512.   Mouse Up Location: Location of 1st mouse-up in a single, double, or triple-click, or drag.  Window’s local co-ordinates are used.
  513.  
  514.  
  515. Poll.Mouse.Up[1].When
  516. `````````````````````
  517.   Mouse Up Time: Time of 1st mouse-up.  Number of “ticks” since startup.
  518.  
  519.  
  520. Poll.Mouse.Up[1].Modifiers
  521. ``````````````````````````
  522.   Mouse Up Modifier Record: Event modifiers at the time of the 1st mouse-up event.  See the note on modifiers below.
  523.  
  524.  
  525. Poll.Mouse.Up[2]…
  526. `````````````````
  527.   Mouse-Up Array Record: Same fields, but for 2nd mouse-up in a double, or triple-click, or drag.
  528.  
  529.  
  530. Poll.Mouse.Up[3]…
  531. `````````````````
  532.   Mouse-Up Array Record: Same fields, but for 3rd mouse-up in a triple-click, or drag.
  533.  
  534.  
  535. Poll.Mouse.Where
  536. ````````````````
  537.   Mouse Location: Current mouse location in window’s local co-ordinates.
  538.  
  539.  
  540. Poll.Modifiers
  541. ``````````````
  542.   Modifier Record: Event modifiers at the time when the event occurred.  See the note on modifiers below.
  543.  
  544.  
  545. Poll.Event
  546. ``````````
  547.   The Event Manager’s Event Record: A completely unaltered event record as retrieved from the Toolbox Event Manager.  This is used for applications that want to process their own custom events or custom controls.
  548.  
  549.  
  550.  
  551. Note: For C programmers…  The polling record’s arrays are documented as
  552.       using Pascal nomenclature (the elements are numbered 1, 2 and 3).
  553.       In C, the same array’s elements are numbered 0, 1 and 2 (they
  554.       start at zero).  In this manual when C programmers read:
  555.           Poll.Mouse.Down[1].Where
  556.       it indicates the first element of the array, which translates to
  557.       the following C source code:
  558.           Poll.Mouse.Down[0].Where
  559.